Common Pitfalls & Best Practices

When to use SyncState?

You can use SyncState for general purpose state management. It only helps to adopt realtime and multi-user functionalities at a later stage.

It's well suited for document based multiuser apps like Google Docs and Figma.

useDoc vs store.useDoc

Keep in mind that useDoc hook, in addition to fetching the state and setter function, manages the reactivity for your component.

Do not confuse the hook with the method store.useDoc. This method is the same as useDoc hook except for reactivity. If you are not using React, you can use store.observe method to subscribe to changes in the document.

depth in useDoc, observe and intercept

The depth argument in useDoc, observe and intercept lets you define the reactivity to different levels of path.

For example, consider the following store

const store = createDocStore({ app: { todos: [] } });

If your component uses useDoc("/app/todos", 0), depth is 0 which means only "/app" and "/app/todos" will trigger an update.

Depth means chunks of path beyond the ones passed to useDoc. Here, if a patch is generated with path "/app/todos/0", this will have depth 1 compared to path "/app/todos" while "/app" has depth -1 and "/app/todos" has depth 0.

So when you pass a depth argument to useDoc, observe or intercept, it means that the listener should be triggered for any patch with depth up to the passed argument (In the above case, depth -1 and 0). We do this because path "/app" means that the value at rootState.app is being changed and that will also change todos inside app. So you have to be careful about the state you are updating. Only update the part of state which is necessary.

For the above example useDoc("/app/todos", 0), we will list the patches which will trigger an update for each depth

0: "/app", "/app/todos"

1: "/app", "/app/todos", "/app/todos/0", "/app/todos/1", ...

2: "/app", "/app/todos", "/app/todos/0", "/app/todos/0/caption", ...

If you pass Infinity as depth, it will trigger an update for the matching paths with any depth.